Exits

The exits.t module provides the status line exit lister and a list of exits in response to an EXITS command or when the player character attempts to travel in a direction where there isn't an exit. There normally isn't any need to exclude the exits module, since the player can always disable the status line exit listing if s/he wishes with an EXITS OFF command. There usually won't be much need for game authors to intervene with the functions of the Exits module either, since they should just work if the module is present. But there are a few features it could be useful for game authors to know about.

One feature the adv3Lite exit lister introduces is the ability to have the status line exit lister show exits that lead to unvisited locations in a different colour (currently the options are red, blue, green and yellow, with green as the current default). The player can enable or disable this feature with the commands EXIT COLOUR|COLOR ON|OFF and can select the colour to be used with the command EXIT COLOUR|COLOR RED|BLUE|GREEN|YELLOW. The game author can also change these settings programmatically (or, more usefully, set the initial values of these setting for a game) by overriding or changing the highlightUnvisitedExits (true or nil) and unvisitedExitColour ('red', 'blue', 'green' or 'yellow') properties on the statuslineExitLister object. (In fact unvisitedExitColour can be set to any value that would be legal in a <FONT COLOR=color> tag).

A room is considered to have been visited if the player character has seen it (i.e., has seen a description of the room when the room was illuminated). Normally it will be clear enough what this means, but one special case may need explaining further. If a direction property of a room is implemented as a method (instead of pointing to a TravelConnector, Door or Room), the exit will be shown in the status line exit lister, and originally shown as unvisited. Once the player character has attempted to traverse the exit, its destination will be shown as visited, even if the exit doesn't actually lead anywhere. In practice, this is normally the desired behaviour, since the distinctive colouring of unvisited exits in the status line exit lister is intended as an indication of which exits might still need exploring, and an exit that doesn't lead anywhere doesn't need any further exploration.

Internally, the library keeps a record of where exits implemented as methods lead to in a LookupTable on libGlobal.extraDestInfo. It adds entries to this table whenever an exit implemented as a method is traversed, noting where the player character actually ends up. By default (when there's no entry) this LookupTable returns a value of unknownDest_, which is a dummy destination that is never visited (so that initially any exit implemented as a method will be shown as leading to an unvisited location, since the library will regard it as leading to unknownDest_). Once the player character tries to go via such an exit, the actual destination where the player character ends up is stored in libGlobal.extraDestInfo, even if the player in fact stays put (in which case his current location will be recorded as the destination). Since the player character current location (or indeed, anywhere else the player character ends up) always counts as visited (unless it's dark), from then on the corresponding exit will be shown as leading to a visited location.

By default, the response to an explicit EXITS command will show the name (or rather destName) of any known destinations along with the directions that lead to them (for this purpose a destination is known if it has been visited or is otherwise familiar). If you want to suppress the inclusion of (known) destination names you can so by setting explicitExitLister.showDestNames to nil.

Customizing how Exits are Listed

There are four properties of the Room class you can use to customize the way exits are listed when the player character is in a specific room. All of these should be defines on a specific room (or a class of Room).

noExits: If this is defined as either a single-quoted string or a method that returns a single-quoted string, then the status-line exit lister will use that string in place of the default None if there are no exits (or no apparent exits) from the room. This may be useful, for example, when None could be potentially misleading because there is a way out of the room that the player has to find.

listStatusExits(lst, cnt): this can be defined to display text in place of the normal list of exits, where lst is the list of DestInfo objects encapsulating the exits and cnt is the number of exits. The relevant properties of DestInfo objects are dir_, the Direction in which the exit leads, and dest_, the destination to which it leads. It may be be useful to define this method if, for example, we want to hide exits in a maze or represent a situation where the player has become disoriented. For example we might define:

listStatusExits(lst, cnt) { "confusing!"; }

listExits(lst, cnt): This can be defined in much the same way as listStatusExits(lst, cnt) to change the way exits in the room are listed in response to an explicit EXITS command or as part of a cannot go that way message, for example:

listExits(lst, cnt) { "<<cnt>> different ways"; }

In this case the text you display will follow "From here you could go ". You can change this to something else by defining exitListPrefix(cnt) on the room (where cnt is once again the number of exits), e.g.:

exitListPrefix(cnt) { "Leading off from here <<cnt > 1 ? 'are' : 'is'>> "; }

Returning true from listExits() or listStatusExits() allows the normal listing of exits to go ahead. This might be useful if, for example, we only want exits to be listed when a room is illuminated:

   listStatusExits(lst, cnt)
   {
      if(isIlluminated)
         return true;
      
      "too dark to discern";
      return nil;
   }

This all assumes that you want to change the way exits are shown for specific rooms. To customise the exit listers globally you can follow the suggestions in the section on Listers. The listers to modify would be the statuslineExitLister and/or the explicitExitLister.